home *** CD-ROM | disk | FTP | other *** search
/ Visual Cafe 3 / Visual Cafe 3.ISO / Vcafe / Main.bin / FontMetrics.java < prev    next >
Text File  |  1998-09-22  |  13KB  |  338 lines
  1. /*
  2.  * @(#)FontMetrics.java    1.18 98/07/01
  3.  *
  4.  * Copyright 1995-1998 by Sun Microsystems, Inc.,
  5.  * 901 San Antonio Road, Palo Alto, California, 94303, U.S.A.
  6.  * All rights reserved.
  7.  * 
  8.  * This software is the confidential and proprietary information
  9.  * of Sun Microsystems, Inc. ("Confidential Information").  You
  10.  * shall not disclose such Confidential Information and shall use
  11.  * it only in accordance with the terms of the license agreement
  12.  * you entered into with Sun.
  13.  */
  14.  
  15. package java.awt;
  16.  
  17. /** 
  18.  * A font metrics object, which gives information about the rendering 
  19.  * of a particular font on a particular screen. Note that the 
  20.  * implementations of these methods are inefficient, they are usually 
  21.  * overridden with more efficient toolkit-specific implementations.
  22.  * <p>
  23.  * <b>Note to subclassers</b>: Since many of these methods form closed
  24.  * mutually recursive loops, you must take care that you implement
  25.  * at least one of the methods in each such loop in order to prevent
  26.  * infinite recursion when your subclass is used.
  27.  * In particular, the following is the minimal suggested set of methods
  28.  * to override in order to ensure correctness and prevent infinite
  29.  * recursion (though other subsets are equally feasible):
  30.  * <ul>
  31.  * <li><a href=#getAscent>getAscent</a>()
  32.  * <li><a href=#getAscent>getDescent</a>()
  33.  * <li><a href=#getLeading>getLeading</a>()
  34.  * <li><a href=#getMaxAdvance>getMaxAdvance</a>()
  35.  * <li><a href="#charWidth(char)">charWidth</a>(char ch)
  36.  * <li><a href="#charsWidth(char[], int, int)">charsWidth</a>(char data[], int off, int len)
  37.  * </ul>
  38.  * <p>
  39.  * <img src="images-awt/FontMetrics-1.gif" border=15 align
  40.  * ALIGN=right HSPACE=10 VSPACE=7>
  41.  * When an application asks AWT to place a character at the position 
  42.  * (<i>x</i>, <i>y</i>), the character is placed so that its 
  43.  * reference point (shown as the dot in the accompanying image) is 
  44.  * put at that position. The reference point specifies a horizontal 
  45.  * line called the <i>baseline</i> of the character. In normal 
  46.  * printing, the baselines of characters should align. 
  47.  * <p> 
  48.  * In addition, every character in a font has an <i>ascent</i>, a 
  49.  * <i>descent</i>, and an <i>advance width</i>. The ascent is the 
  50.  * amount by which the character ascends above the baseline. The 
  51.  * descent is the amount by which the character descends below the 
  52.  * baseline. The advance width indicates the position at which AWT  
  53.  * should place the next character. 
  54.  * <p>
  55.  * If the current character is placed with its reference point 
  56.  * at the position (<i>x</i>, <i>y</i>), and 
  57.  * the character's advance width is <i>w</i>, then the following 
  58.  * character is placed with its reference point at the position 
  59.  * (<i>x </i><code>+</code><i> w</i>, <i>y</i>). 
  60.  * The advance width is often the same as the width of character's 
  61.  * bounding box, but need not be so. In particular, oblique and 
  62.  * italic fonts often have characters whose top-right corner extends 
  63.  * slightly beyond the advance width. 
  64.  * <p>
  65.  * An array of characters or a string can also have an ascent, a 
  66.  * descent, and an advance width. The ascent of the array is the 
  67.  * maximum ascent of any character in the array. The descent is the 
  68.  * maximum descent of any character in the array. The advance width 
  69.  * is the sum of the advance widths of each of the characters in the 
  70.  * array. 
  71.  * @version     1.18 07/01/98
  72.  * @author     Jim Graham
  73.  * @see         java.awt.Font
  74.  * @since       JDK1.0
  75.  */
  76. public abstract class FontMetrics implements java.io.Serializable {
  77.     /**
  78.      * The actual font.
  79.      * @see #getFont
  80.      * @since JDK1.0
  81.      */
  82.     protected Font font;
  83.  
  84.     /*
  85.      * JDK 1.1 serialVersionUID 
  86.      */
  87.     private static final long serialVersionUID = 1681126225205050147L;
  88.  
  89.     /**
  90.      * Creates a new <code>FontMetrics</code> object for finding out 
  91.      * height and width information about the specified font and  
  92.      * specific character glyphs in that font. 
  93.      * @param     font the font
  94.      * @see       java.awt.Font
  95.      * @since     JDK1.0
  96.      */
  97.     protected FontMetrics(Font font) {
  98.     this.font = font;
  99.     }
  100.  
  101.     /**
  102.      * Gets the font described by this font metric.
  103.      * @return    the font described by this font metric.
  104.      * @since     JDK1.0
  105.      */
  106.     public Font getFont() {
  107.     return font;
  108.     }
  109.  
  110.     /**
  111.      * Determines the <em>standard leading</em> of the font described by 
  112.      * this font metric. The standard leading (interline spacing) is the 
  113.      * logical amount of space to be reserved between the descent of one 
  114.      * line of text and the ascent of the next line. The height metric is 
  115.      * calculated to include this extra space. 
  116.      * @return    the standard leading of the font.
  117.      * @see       java.awt.FontMetrics#getHeight
  118.      * @see       java.awt.FontMetrics#getAscent
  119.      * @see       java.awt.FontMetrics#getDescent
  120.      * @since     JDK1.0
  121.      */
  122.     public int getLeading() {
  123.     return 0;
  124.     }
  125.  
  126.     /**
  127.      * Determines the <em>font ascent</em> of the font described by this 
  128.      * font metric. The font ascent is the distance from the font's 
  129.      * baseline to the top of most alphanumeric characters. Some 
  130.      * characters in the font may extend above the font ascent line. 
  131.      * @return     the font ascent of the font.
  132.      * @see        java.awt.FontMetrics#getMaxAscent
  133.      * @since      JDK1.0
  134.      */
  135.     public int getAscent() {
  136.     return font.getSize();
  137.     }
  138.  
  139.     /**
  140.      * Determines the <em>font descent</em> of the font described by this 
  141.      * font metric. The font descent is the distance from the font's 
  142.      * baseline to the bottom of most alphanumeric characters with 
  143.      * descenders. Some characters in the font may extend below the font 
  144.      * descent line. 
  145.      * @return     the font descent of the font.
  146.      * @see        java.awt.FontMetrics#getMaxDescent
  147.      * @since      JDK1.0
  148.      */
  149.     public int getDescent() {
  150.     return 0;
  151.     }
  152.  
  153.     /**
  154.      * Gets the standard height of a line of text in this font.  This
  155.      * is the distance between the baseline of adjacent lines of text.
  156.      * It is the sum of the leading + ascent + descent.  There is no
  157.      * guarantee that lines of text spaced at this distance will be
  158.      * disjoint; such lines may overlap if some characters overshoot
  159.      * either the standard ascent or the standard descent metric.
  160.      * @return    the standard height of the font.
  161.      * @see       java.awt.FontMetrics#getLeading
  162.      * @see       java.awt.FontMetrics#getAscent
  163.      * @see       java.awt.FontMetrics#getDescent
  164.      * @since     JDK1.0
  165.      */
  166.     public int getHeight() {
  167.     return getLeading() + getAscent() + getDescent();
  168.     }
  169.  
  170.     /**
  171.      * Determines the maximum ascent of the font described by this font 
  172.      * metric. No character extends further above the font's baseline 
  173.      * than this height. 
  174.      * @return    the maximum ascent of any character in the font.
  175.      * @see       java.awt.FontMetrics#getAscent
  176.      * @since     JDK1.0
  177.      */
  178.     public int getMaxAscent() {
  179.     return getAscent();
  180.     }
  181.  
  182.     /**
  183.      * Determines the maximum descent of the font described by this font 
  184.      * metric. No character extends further below the font's baseline 
  185.      * than this height. 
  186.      * @return    the maximum descent of any character in the font.
  187.      * @see       java.awt.FontMetrics#getDescent
  188.      * @since     JDK1.0
  189.      */
  190.     public int getMaxDescent() {
  191.     return getDescent();
  192.     }
  193.  
  194.     /**
  195.      * For backward compatibility only.
  196.      * @see #getMaxDescent
  197.      * @deprecated As of JDK version 1.1.1,
  198.      * replaced by <code>getMaxDescent()</code>.
  199.      */
  200.     public int getMaxDecent() {
  201.     return getMaxDescent();
  202.     }
  203.  
  204.     /**
  205.      * Gets the maximum advance width of any character in this Font. 
  206.      * The advance width is the amount by which the current point is
  207.      * moved from one character to the next in a line of text.
  208.      * @return    the maximum advance width of any character 
  209.      *            in the font, or <code>-1</code> if the 
  210.      *            maximum advance width is not known.
  211.      * @since     JDK1.0
  212.      */
  213.     public int getMaxAdvance() {
  214.     return -1;
  215.     }
  216.  
  217.     /** 
  218.      * Returns the advance width of the specified character in this Font.
  219.      * The advance width is the amount by which the current point is
  220.      * moved from one character to the next in a line of text.
  221.      * @param ch the character to be measured
  222.      * @return    the advance width of the specified <code>char</code> 
  223.      *                 in the font described by this font metric.
  224.      * @see       java.awt.FontMetrics#charsWidth
  225.      * @see       java.awt.FontMetrics#stringWidth
  226.      * @since     JDK1.0
  227.      */
  228.     public int charWidth(int ch) {
  229.     return charWidth((char)ch);
  230.     }
  231.  
  232.     /** 
  233.      * Returns the advance width of the specified character in this Font.
  234.      * The advance width is the amount by which the current point is
  235.      * moved from one character to the next in a line of text.
  236.      * @param ch the character to be measured
  237.      * @return     the advance width of the specified <code>char</code> >
  238.      *                  in the font described by this font metric.
  239.      * @see        java.awt.FontMetrics#charsWidth
  240.      * @see        java.awt.FontMetrics#stringWidth
  241.      * @since      JDK1.0
  242.      */
  243.     public int charWidth(char ch) {
  244.     if (ch < 256) {
  245.         return getWidths()[ch];
  246.     }
  247.     char data[] = {ch};
  248.     return charsWidth(data, 0, 1);
  249.     }
  250.  
  251.     /** 
  252.      * Returns the total advance width for showing the specified String
  253.      * in this Font.
  254.      * The advance width is the amount by which the current point is
  255.      * moved from one character to the next in a line of text.
  256.      * @param str the String to be measured
  257.      * @return    the advance width of the specified string 
  258.      *                  in the font described by this font metric.
  259.      * @see       java.awt.FontMetrics#bytesWidth
  260.      * @see       java.awt.FontMetrics#charsWidth
  261.      * @since     JDK1.0
  262.      */
  263.     public int stringWidth(String str) {
  264.     int len = str.length();
  265.     char data[] = new char[len];
  266.     str.getChars(0, len, data, 0);
  267.     return charsWidth(data, 0, len);
  268.     }
  269.  
  270.     /** 
  271.      * Returns the total advance width for showing the specified array
  272.      * of characters in this Font.
  273.      * The advance width is the amount by which the current point is
  274.      * moved from one character to the next in a line of text.
  275.      * @param data the array of characters to be measured
  276.      * @param off the start offset of the characters in the array
  277.      * @param len the number of characters to be measured from the array
  278.      * @return    the advance width of the subarray of the specified 
  279.      *               <code>char</code> array in the font described by 
  280.      *               this font metric.
  281.      * @see       java.awt.FontMetrics#charWidth(int)
  282.      * @see       java.awt.FontMetrics#charWidth(char)
  283.      * @see       java.awt.FontMetrics#bytesWidth
  284.      * @see       java.awt.FontMetrics#stringWidth
  285.      * @since     JDK1.0
  286.      */
  287.     public int charsWidth(char data[], int off, int len) {
  288.     return stringWidth(new String(data, off, len));
  289.     }
  290.  
  291.     /** 
  292.      * Returns the total advance width for showing the specified array
  293.      * of bytes in this Font.
  294.      * The advance width is the amount by which the current point is
  295.      * moved from one character to the next in a line of text.
  296.      * @param data the array of bytes to be measured
  297.      * @param off the start offset of the bytes in the array
  298.      * @param len the number of bytes to be measured from the array
  299.      * @return    the advance width of the subarray of the specified 
  300.      *               <code>byte</code> array in the font described by 
  301.      *               this font metric.
  302.      * @see       java.awt.FontMetrics#charsWidth
  303.      * @see       java.awt.FontMetrics#stringWidth
  304.      * @since     JDK1.0
  305.      */
  306.     public int bytesWidth(byte data[], int off, int len) {
  307.     return stringWidth(new String(data, 0, off, len));
  308.     }
  309.  
  310.     /**
  311.      * Gets the advance widths of the first 256 characters in the Font.
  312.      * The advance width is the amount by which the current point is
  313.      * moved from one character to the next in a line of text.
  314.      * @return    an array giving the advance widths of the 
  315.      *                 characters in the font 
  316.      *                 described by this font metric.
  317.      * @since     JDK1.0
  318.      */
  319.     public int[] getWidths() {
  320.     int widths[] = new int[256];
  321.     for (char ch = 0 ; ch < 256 ; ch++) {
  322.         widths[ch] = charWidth(ch);
  323.     }
  324.     return widths;
  325.     }
  326.  
  327.     /** 
  328.      * Returns a representation of this <code>FontMetric</code> 
  329.      * object's values as a string.
  330.      * @return    a string representation of this font metric.
  331.      * @since     JDK1.0.
  332.      */
  333.     public String toString() {
  334.     return getClass().getName() + "[font=" + getFont() + "ascent=" +
  335.         getAscent() + ", descent=" + getDescent() + ", height=" + getHeight() + "]";
  336.     }
  337. }
  338.